/**
 * Copyright (c) 2013-2022 Nikita Koksharov
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.redisson.api;

import java.util.concurrent.TimeUnit;


/**
 * 一个支持令牌管理的分布式锁接口，继承自RLock和RFencedLockAsync。
 * 该接口提供了获取锁并同时返回令牌的方法，用于实现精细的权限控制和锁的释放管理。
 */
public interface RFencedLock extends RLock, RFencedLockAsync {

    /**
     * 获取当前锁的令牌。
     * @return 当前锁的令牌，用于标识和管理锁的状态。
     */
    Long getToken();

    /**
     * 尝试获取锁并返回锁的令牌。
     * @return 如果成功获取锁，则返回锁的令牌；否则返回null。
     */
    Long lockAndGetToken();

    /**
     * 尝试获取锁并返回锁的令牌，设置锁的租期。
     * @param leaseTime 锁的租期，指定锁自动释放的时间。
     * @param unit 时间单位。
     * @return 如果成功获取锁，则返回锁的令牌；否则返回null。
     */
    Long lockAndGetToken(long leaseTime, TimeUnit unit);

    /**
     * 尝试在指定等待时间内获取锁并返回锁的令牌。
     * @return 如果成功获取锁，则返回锁的令牌；否则返回null。
     */
    Long tryLockAndGetToken();

    /**
     * 尝试在指定等待时间内获取锁并返回锁的令牌，设置锁的租期。
     * @param waitTime 等待获取锁的最长时间。
     * @param unit 时间单位。
     * @return 如果成功获取锁，则返回锁的令牌；否则返回null。
     */
    Long tryLockAndGetToken(long waitTime, TimeUnit unit);

    /**
     * 尝试在指定等待时间内获取锁并返回锁的令牌，同时设置锁的租期。
     * @param waitTime 等待获取锁的最长时间。
     * @param leaseTime 锁的租期，指定锁自动释放的时间。
     * @param unit 时间单位。
     * @return 如果成功获取锁，则返回锁的令牌；否则返回null。
     */
    Long tryLockAndGetToken(long waitTime, long leaseTime, TimeUnit unit);
}

